Errors and paging topic

Handle failures, cancel and retry requests, and walk paged lists.

Error handling

PlexException

Every call throws a PlexException on failure:

try {
  await plex.library.sections();
} on PlexException catch (e) {
  print('${e.type} ${e.statusCode} ${e.message}');
}

PlexErrorType is one of connection, timeout, auth, passRequired, notFound, badRequest, serverError, parse, state, cancelled and unknown. The exception also carries the request path, the underlying cause, the original stackTrace, the whole error body the server sent (message holds at most its first 512 bytes) and, when the server sent Retry-After (on a 429 or 503), retryAfter. The value of an X-Plex-Token, deviceJWT or pin in the path or the message reads REDACTED, so toString() can be logged as it is. body and cause are kept as they came.

An empty answer

A call that looks one thing up (get, item, details, byId, person, liveSession) returns null when the answer holds nothing. A call that creates something (playlists.create, collections.create, playQueues.create, downloadQueue.create) throws a parse error when the answer does not hold it. subscriptions.create returns null instead: what PMS answers to it is not verified.

A call that lists (sections, children, playlists.items, …) throws a parse error for an answer without a MediaContainer, and returns an empty list for a container that holds no entries. A call that answers a raw map (library.itemTree, topUsers, sectionCommon, streamLevels, …) returns an empty map for an empty answer, and server.transientToken returns null when the answer names no token.

Wrong arguments are not a PlexException: an id that is empty, . or .., a missing or contradictory combination of parameters, a negative time, throw an ArgumentError before anything is sent. A call that returns a Future reports it through that Future, never while it is being called; a URL builder, which answers at once, throws at once. So do PlexDeviceKey.fromSeed for a seed of the wrong length, while PlexDeviceKey.fromJson and PlexJwtSession.fromJson throw a FormatException for stored JSON they cannot read.

Classifying a failure

try {
  await plex.library.sections();
} on PlexException catch (e) {
  if (e.isCancelled) {
    // the caller gave up: not a failure, ignore it
  } else if (e.isPassRequired) {
    showPassNeeded(); // remote video needs a Plex Pass or Remote Watch Pass
  } else if (e.isAuthError) {
    // 401 or 498: the token is refused. A 403 can also be a valid token
    // that may not do this (a shared user on an owner's route): check
    // e.statusCode before signing the user out.
    await signInAgain();
  } else if (e.isTransient) {
    scheduleRetry(e.retryAfter); // network, 5xx or 429
  } else if (e.isNotFound) {
    showGone(); // 404: confirmed absence
  } else {
    showError(e.message);
  }
}
Getter True for
isNetworkFailure No answer at all: the connection failed or timed out
isTransient A failure that may pass if sent again: a network failure, a 5xx or a 429
isNotFound The server answered 404
isCancelled The request was cancelled through a PlexCancelToken
isAuthError 401, 403 or 498 (plex.tv's "token expired"), or a sign-in answered without a token
isPassRequired Playback refused for want of a Plex Pass or Remote Watch Pass (see Streaming); not an auth error

After useJwt() the client renews an expired JWT on its own, and retries the refused request once; tokenRenewer does the same for tokens you renew yourself. Otherwise, on isAuthError, sign in again (see Client and sign-in).

Cancellation and retries

Cancelling requests

PlexCancelToken? searchToken;

Future<List<PlexHub>> searchAsYouType(PlexClient plex, String text) async {
  searchToken?.cancel(); // drop the previous keystroke's request
  final token = searchToken = PlexCancelToken();
  try {
    return await plex.withCancelToken(token).search.hubs(query: text);
  } on PlexException catch (e) {
    if (e.isCancelled) return const [];
    rethrow;
  }
}

withCancelToken(token) returns a view of the client whose every call is cancelled by token.cancel(). The view shares the client's connections, server and token (connect, setToken and close on either affect both) and costs nothing to create, so make one per page, filter or search term. A token cancels once: make a new one for the next request. request(), requestBytes(), requestStream() and downloadToFile() also take a cancelToken directly.

A cancelled call throws a PlexException of type cancelled. notifications is the same object on the view as on the client: a WebSocket is not a request and is not cancelled.

Retry policy

final plex = PlexClient(
  credentials: credentials,
  retryPolicy: const PlexRetryPolicy(
    maxAttempts: 4, // the first attempt included
    maxDelay: Duration(seconds: 10),
  ),
);

Retries are off by default. With a policy, only GET and HEAD requests are sent again, and only after a failure another attempt can fix: no answer (connection lost, timeout), 502, 503, 504 or 429. A 500 is not retried. The wait grows exponentially from initialDelay (300 ms) with random jitter, never above maxDelay (5 s); a Retry-After header is honoured up to maxDelay, and a cancel token cancels the wait too. const PlexRetryPolicy() sends a request up to three times. Opening a stream is retried as well; a body already flowing is not replayed.

Paging

Page parameters

Plex pages with X-Plex-Container-Start and X-Plex-Container-Size, and pages only when it gets both, so every paged call sends both.

allByType(), albums(), playlists.list(), sessions.history() and hubs.drill() always read one page: 50 rows from start unless you pass size. children(), grandchildren(), allLeaves(), recentlyAdded() and playlists.items() return every row when you pass neither, and one page when you pass size (start is 0 by default). Pass start together with size: a start alone throws an ArgumentError, since the server would ignore it.

Walking every page

final tracks = PlexPaging.items(
  (start, size) => plex.library.grandchildren(
    ratingKey: artist.ratingKey,
    start: start,
    size: size,
  ),
  pageSize: 200,
);
await for (final track in tracks) {
  print(track.title);
}

// allByType returns a container: hand PlexPaging its items.
final albumPages = PlexPaging.pages(
  (start, size) async => (await plex.library.allByType(
    sectionId: musicLib.id,
    type: PlexMetadataType.album,
    start: start,
    size: size,
  ))
      .items,
  limit: 500,
);

PlexPaging.pages() streams one page at a time and items() the rows one by one. Paging stops at the first page shorter than pageSize (100 by default) or once limit rows have arrived, asking the last page for exactly what is left. Each page is one request, made as the stream is listened to; cancelling the subscription stops the requests. Pair it with a cancel token (see Cancelling requests above) to drop the request in flight too.

Classes

PlexCancelToken Errors and paging
Cancels requests that are still in flight.
PlexPaging Errors and paging
Walk a paged endpoint page by page.
PlexRetryPolicy Errors and paging
When and how often to resend a request that failed transiently.

Enums

PlexErrorType Errors and paging
Semantic categories for failures coming out of PlexClient.

Exceptions / Errors

PlexException Errors and paging
Exception thrown by PlexClient for any failed operation.